Sonar FAQ
Answers about the current public API, cloud device connections, data, and webhooks.
Which device connection types are available today?
The current developer release supports cloud API providers through Sonar’s hosted authorization flow. Query GET /v1/providers for the authoritative catalog. Atlas uses the same list.
Apple Health, Health Connect, and Samsung Health connect through the Mobile SDKs embedded in your mobile application.
Where do I get a provider slug?
Query GET /v1/providers. Each result includes the exact slug accepted by connection and disconnection requests, plus its display name and nullable thumbnail URL.
Can I list a user's connected devices through the public API?
Yes. Retrieve the user with GET /v1/users/{id} and inspect its connections. Each entry includes the provider, connection status, connection timestamp, and nullable latest synchronization timestamp.
Does sandbox automatically seed health data?
No. Sandbox isolates test users, keys, events, and webhooks from live, but new users begin without data. Connect a supported provider to populate data. A sandbox organization can have at most 50 connected devices.
How do I fetch health scores?
From GET /v1/users/{id}/scores, which returns sleep_score, recovery_score, strain_score, nutrition_score, and stress_score in the daily columnar shape plus a latest block per score. Score IDs are not accepted by /daily.
Why is a daily value null?
Sonar returns every date in the requested range. A value is null when no consolidated reading is available for that metric and date, including before the provider’s first sync or while historical data is still arriving.
How much daily data can I request at once?
Up to 366 inclusive days. When no dates are supplied, the API returns the latest 30-day window ending on the current date in the user’s profile timezone. If the profile has no timezone, Sonar uses UTC.
Which timezone does the API use?
Operational metadata such as created_at, connected_at, last_sync_at, and webhook at is always UTC and ends in Z. Health dates, workout and sleep times, and time-series buckets use the API user’s profile timezone. See The Health-Data Clock for the complete parsing rules and daylight-saving behavior.
Can I request imperial units or raw provider payloads?
No. The current API returns normalized values in canonical units. It does not expose a unit-system parameter, raw provider payloads, or per-value source attribution.
When is data ready after the authorization redirect?
The redirect confirms that authorization completed. Ingestion is asynchronous. Subscribe to device.connected to confirm the connection and subject.synced to react whenever data is processed. Historical data can arrive across multiple sync events and has no separate completion event.
How much historical data can Sonar retrieve?
When a user connects a cloud provider, Sonar automatically retrieves historical data, with the default lookback period varying by provider. Extended historical retrieval may be available, subject to provider limits, user permissions, and the records available in the connected account. Contact us to discuss the historical coverage available for your use case.
Historical data becomes available progressively through the API as it is imported and processed.
How are webhook requests authenticated?
Verify X-Sonar-Signature, an HMAC-SHA256 digest of the exact raw body using the endpoint’s signing secret. Also deduplicate on event_id because delivery is at least once.
Is there a public events endpoint?
No. Events and delivery outcomes are visible in the Developers workspace. External systems receive subscribed events through webhooks.
What happens when I delete a user?
The API returns 202 and completes deletion asynchronously. Sonar disconnects providers, removes stored health data, emits subject.deleted, and finally removes the user from listings.
Can I call the API directly from a browser or mobile app?
Do not expose an API key in client software. The current public API is server-to-server; proxy the required operation through your backend.
What are the rate limits?
By default, API keys have a rate limit of 600 requests per minute, with a burst capacity of 100 requests. For larger deployments or higher-throughput workloads, contact us to arrange custom rate limits and capacity planning. We’ll work with your team to establish limits suited to your expected usage before launch and as you scale.
When limited, wait for the number of seconds in Retry-After before retrying.